nfc_ker_lib.h File Reference

Go to the source code of this file.

Macros
#define	NFC_KER_OPT_DEBUG   0x0001
	Check option definitions. More...
#define	NFC_KER_OPT_RRP   0x0002
#define	NFC_KER_OPT_BIN_RANGE   0x0004
#define	NFC_GET_DATA_OPT_CUST   0x0001
#define	NFC_GET_DATA_OPT_SKIP_STD_PROC   0x0002

Typedefs
typedef struct tag_KER_TRAN	KER_TRAN
typedef KER_BOOL(KER_API *	F_NFC_KER_CHECK_OPT) (KER_CTX_PARAM KER_TRAN *pTran, KER_INT16U usOption, KER_INT16U usParam, KER_VOID *pParam)
	Checks kernel option callback. More...
typedef KER_RES(KER_API *	F_NFC_KER_INIT) (KER_CTX_INIT_PARAM const KER_VOID *pConfigID, KER_INT16U usConfigIDLen, const KER_CHAR *pchKernelFiles, KER_INT16U usKernelFilesLen)
	Performs kernel initialization. More...
typedef KER_RES(KER_API *	F_NFC_KER_DEINIT) (KER_CTX_SINGLE_PARAM)
	Performs kernel de-initialization. More...
typedef KER_BOOL(KER_API *	F_NFC_KER_VERINFO) (KER_CTX_PARAM KER_CHAR **ppchEmvVer, KER_INT16U *pusEmvVerLen, KER_CHAR **ppchLibVer, KER_INT16U *pusLibVerLen)
	Obtains emv kernel library version info. More...
typedef KER_RES(KER_API *	F_NFC_KER_TRAN_PREPROCESS) (KER_CTX_PARAM KER_INT16U usOptions, const NFC_EP_PRE_DATA *pEpPRE)
	Makes transaction preprocessing by kernel (optional) More...
typedef KER_RES(KER_API *	F_NFC_KER_TRAN_START) (KER_CTX_PARAM const NFC_EP_PRE_DATA *pEpPRE, const NFC_EP_PPSE_DATA *pEpPPSE, const NFC_EP_TRAN_DATA *pEpTranData, KER_TRAN **ppTran, NFC_OUTCOME **ppOutcome)
	Initiates transaction processing by kernel. More...
typedef KER_RES(KER_API *	F_NFC_KER_TRAN_ISS_UPDATE) (KER_CTX_PARAM KER_TRAN *pTran, const NFC_EP_RESTART_DATA *pEpRestartData, const NFC_EXT_TERM_RESTART_DATA *pTermRestartData, NFC_OUTCOME **ppOutcome)
	Initiates transaction bprocessing by kernel. More...
typedef KER_BOOL(KER_API *	F_NFC_KER_TRAN_RELEASE) (KER_CTX_PARAM KER_TRAN *pTran)
	Releases NFC Transaction container structure. More...
typedef KER_RES(KER_API *	F_NFC_KER_GET_DATA) (KER_CTX_PARAM KER_TRAN *pTran, KER_INT16U usOptions, KER_BYTE *pbtData, KER_INT16U *pusDataLen)
	Transaction data request. More...
typedef KER_RES(KER_API *	F_NFC_KER_GET_DATA_BY_TAG) (KER_CTX_PARAM KER_TRAN *pTran, KER_INT16U usOptions, const KER_BYTE *pbtTag, KER_BYTE btTagSize, KER_BYTE *pbtData, KER_INT16U *pusDataSize)
	transaction data request More...
typedef KER_RES(KER_API *	F_NFC_KER_GET_DATA_BY_TAG_LIST) (KER_CTX_PARAM KER_TRAN *pTran, KER_INT16U usOptions, const KER_BYTE *pbtTagList, KER_INT16U usTagListSize, KER_BYTE *pbtData, KER_INT16U *pusDataSize)
	transaction data request More...

Detailed Description

NFC KERNEL library export functions which should be called by Entry Point (EP)

Macro Definition Documentation

NFC_GET_DATA_OPT_CUST

#define NFC_GET_DATA_OPT_CUST   0x0001

also look in custom data, not recognized by EMVCo

NFC_GET_DATA_OPT_SKIP_STD_PROC

#define NFC_GET_DATA_OPT_SKIP_STD_PROC   0x0002

skip standard lookup algorithm, proceed to custom data

NFC_KER_OPT_BIN_RANGE

#define NFC_KER_OPT_BIN_RANGE   0x0004

BIN Range check

NFC_KER_OPT_DEBUG

#define NFC_KER_OPT_DEBUG   0x0001

Check option definitions.

Debug mode check

NFC_KER_OPT_RRP

#define NFC_KER_OPT_RRP   0x0002

RRP mode check

Typedef Documentation

F_NFC_KER_CHECK_OPT

typedef KER_BOOL(KER_API * F_NFC_KER_CHECK_OPT) (KER_CTX_PARAM KER_TRAN *pTran, KER_INT16U usOption, KER_INT16U usParam, KER_VOID *pParam)

Checks kernel option callback.

Parameters

[in]	pTran	- pointer to the transaction structure (obtained by F_NFC_KER_TRAN_START)
[in]	usOption	- option to check (NFC_KER_OPT_DEBUG, NFC_KER_OPT_RRP)
[in]	usParam	- reserved.
[in]	pParam	- reserved.

Returns

KER_TRUE Option set.

KER_FALSE Option not set.

F_NFC_KER_DEINIT

typedef KER_RES(KER_API * F_NFC_KER_DEINIT) (KER_CTX_SINGLE_PARAM)

Performs kernel de-initialization.

Returns

KER_OK Success.

Other - failure.

Terminal Application should de-init kernel by this function

Warning

Do not call this function if F_NFC_KER_INIT failed.

F_NFC_KER_GET_DATA

typedef KER_RES(KER_API * F_NFC_KER_GET_DATA) (KER_CTX_PARAM KER_TRAN *pTran, KER_INT16U usOptions, KER_BYTE *pbtData, KER_INT16U *pusDataLen)

Transaction data request.

call this function to obtain transaction data from kernel (as a flat TLV with all data available)

Parameters

[in]	pTran	- pointer to the transaction structure (obtained by F_NFC_KER_INIT)
[in]	usOptions	- get options (bitmask), reserved
[out]	pbtData	- Buffer to obtain transaction data (in TLV) (path KER_NULL if you need to calculate tran data length only)
[in,out]	pusDataLen	- Size of Buffer pbtData as input, data length as output

Returns

KER_OK Success

Other Failure

F_NFC_KER_GET_DATA_BY_TAG

typedef KER_RES(KER_API * F_NFC_KER_GET_DATA_BY_TAG) (KER_CTX_PARAM KER_TRAN *pTran, KER_INT16U usOptions, const KER_BYTE *pbtTag, KER_BYTE btTagSize, KER_BYTE *pbtData, KER_INT16U *pusDataSize)

transaction data request

call this function to obtain transaction data by tag from kernel

Parameters

[in]	pTran	- pointer to the transaction structure (obtained by F_NFC_KER_TRAN_START)
[in]	usOptions	- get options (bitmask), reserved
[in]	pbtTag	- buffer with tag value
[in]	btTagSize	- pbtTag value length
[out]	pbtData	- buffer to obtain provided tag value
[in,out]	pusDataSize	- pbtData buffer size as input, output containes result data length

Returns

KER_OK Success

KER_ERR_COMMON_NOT_FOUND Tag not found

Other Failure

F_NFC_KER_GET_DATA_BY_TAG_LIST

typedef KER_RES(KER_API * F_NFC_KER_GET_DATA_BY_TAG_LIST) (KER_CTX_PARAM KER_TRAN *pTran, KER_INT16U usOptions, const KER_BYTE *pbtTagList, KER_INT16U usTagListSize, KER_BYTE *pbtData, KER_INT16U *pusDataSize)

transaction data request

call this function to obtain transaction data by tag list from kernel

Parameters

[in]	pTran	- pointer to the transaction structure (obtained by F_NFC_KER_TRAN_START)
[in]	usOptions	- get options (bitmask), reserved
[in]	pbtTagList	- buffer with tag list
[in]	usTagListSize	- pbtTagList value length
[out]	pbtData	- buffer to obtain provided tag list in TLV format
[in,out]	pusDataSize	- pbtData buffer size as input, output containes result data length

Returns

KER_OK Success

Other Failure

F_NFC_KER_INIT

typedef KER_RES(KER_API * F_NFC_KER_INIT) (KER_CTX_INIT_PARAM const KER_VOID *pConfigID, KER_INT16U usConfigIDLen, const KER_CHAR *pchKernelFiles, KER_INT16U usKernelFilesLen)

Performs kernel initialization.

Parameters

[in]	pConfigID	Buffer with configuration ID obtained from Terminal Application (in HAL recognized format)
[in]	usConfigIDLen	pConfigID buffer length
[in]	pchKernelFiles	buffer with kernel binary file names (for checksum calculation) - set of nul terminated strings ended by nul.
[in]	usKernelFilesLen	length of pchKernelFiles including nul-terminating sym

Returns

KER_OK Success.

Other - failure.

Terminal Application should init kernel by this function before calling any other kernel functions

Warning

If F_NFC_KER_INIT returns KER_OK, Terminal Application should call F_NFC_KER_DEINIT finally to release allocated resources.

F_NFC_KER_TRAN_ISS_UPDATE

typedef KER_RES(KER_API * F_NFC_KER_TRAN_ISS_UPDATE) (KER_CTX_PARAM KER_TRAN *pTran, const NFC_EP_RESTART_DATA *pEpRestartData, const NFC_EXT_TERM_RESTART_DATA *pTermRestartData, NFC_OUTCOME **ppOutcome)

Initiates transaction bprocessing by kernel.

This function initiates NFC issuer update after online request completion

Parameters

[in]	pTran	- pointer to the transaction structure (obtained by F_NFC_KER_TRAN_START)
[in]	pEpRestartData	- Entry Point transaction restart data (last FCI)
[in]	pTermRestartData	- Terminal transaction restart data (issuer update data assumed)
[out]	ppOutcome	- pointer to obtain transaction outcome

Returns

KER_OK Success, see outcome for details.

KER_ERR_COMMON_CARD_HW_ERR Card communication failure - abort transaction

Other errors (Kernel Error Codes) Failure - abort transaction.

Warning

TLV list referenced by ppTranCompletionData if joint to transaction released by F_NFC_KER_TRAN_RELEASE, value of ppTranCompletionData will be reset to KER_NULL in that case.

F_NFC_KER_TRAN_PREPROCESS

typedef KER_RES(KER_API * F_NFC_KER_TRAN_PREPROCESS) (KER_CTX_PARAM KER_INT16U usOptions, const NFC_EP_PRE_DATA *pEpPRE)

Makes transaction preprocessing by kernel (optional)

This function initiates NFC transaction preprocessing by kernel

Parameters

[in]	usOptions	transaction options, set from outside
[in]	pEpPRE	- Entry Point preprocesing data

Returns

KER_OK Success, see outcome for details.

Other errors preprocessing failure

F_NFC_KER_TRAN_RELEASE

typedef KER_BOOL(KER_API * F_NFC_KER_TRAN_RELEASE) (KER_CTX_PARAM KER_TRAN *pTran)

Releases NFC Transaction container structure.

Parameters

[in]

pTran

- pointer to the transaction structure to release (obtained by F_NFC_KER_TRAN_START)

Returns

KER_TRUE Success.

KER_FALSE Failure. Execution failed due to invalid param or memory error.

F_NFC_KER_TRAN_START

typedef KER_RES(KER_API * F_NFC_KER_TRAN_START) (KER_CTX_PARAM const NFC_EP_PRE_DATA *pEpPRE, const NFC_EP_PPSE_DATA *pEpPPSE, const NFC_EP_TRAN_DATA *pEpTranData, KER_TRAN **ppTran, NFC_OUTCOME **ppOutcome)

Initiates transaction processing by kernel.

This function initiates NFC transaction processing by kernel, based on Select command results (from EP)

Parameters

[in]	pEpPRE	- Entry Point preprocesing data
[in]	pEpPPSE	- Entry Point selected aid related PPSE data
[in]	pEpTranData	- transaction data maintained by Entry Point
[out]	ppTran	- pointer to created transaction structure
[out]	ppOutcome	- pointer to obtain transaction outcome

Returns

KER_OK Success, see outcome for details.

KER_ERR_COMMON_CARD_HW_ERR Card communication failure - abort transaction

Other errors (Kernel Error Codes) Failure - abort transaction.

Warning

When tranaction context (ppTran) no longer required call F_NFC_KER_TRAN_RELEASE. Do it despite of result code retuned.

F_NFC_KER_VERINFO

typedef KER_BOOL(KER_API * F_NFC_KER_VERINFO) (KER_CTX_PARAM KER_CHAR **ppchEmvVer, KER_INT16U *pusEmvVerLen, KER_CHAR **ppchLibVer, KER_INT16U *pusLibVerLen)

Obtains emv kernel library version info.

Parameters

[out]	ppchEmvVer	pointer to obtain reference to Kernel Specification version info (optional, set KER_NULL if you don't need it)
[out]	pusEmvVerLen	length of data, including nul-terminated symbol (optional, set KER_NULL if you don't need it)
[out]	ppchLibVer	pointer to obtain reference to kernel library version info (optional, set KER_NULL if you don't need it)
[out]	pusLibVerLen	length of data, including nul-terminated symbol (optional, set KER_NULL if you don't need it)

Returns

KER_TRUE Success.

KER_FALSE Failure. Execution failed due to invalid param.